This file documents all the changes made to SpriteWorld since version 2.0 was released. Many things were changed that will affect you as a user. If you were previously using a version of SpriteWorld prior to version 2.1, it is important that you read through all the changes that have been made since the version you are using was released, and make changes to your source code where necessary. You will only have to do this once, and then will be able to take advantage of the new features in the current version. You should also print out the new versions of the documentation. (Inside SpriteWorld, SpriteWorld - Scrolling, SpriteWorld - Tiling, etc.)
Changes in 2.1.1
SpriteWorld 2.1.1 was a maintenance release that fixed an important bug in the scrolling routines where a NULL pointer was used and could potentially cause a crash.
Changes in 2.1
Tiling changes:
- The TileMap is now created as a single large block, instead of a bunch of tiny blocks (one for each row), and this is now done using Handles instead of Pointers. This has many benefits. The main one is that SWSaveTileMap and SWLoadTileMap require less memory, and the chances of SWSaveTileMap failing for lack of memory is much smaller than it had been previously. The only reason it might fail now is because A) The disk is full, or B) There isn't enough room to load the old TMAP resource that is going to be replaced with the one you're saving (since it must be loaded before RemoveResource can be called to remove it). If the latter of these is the case, your program can simply call UniqueID to save the TileMap using an unused resource ID, so that it can simply be saved, without having to first load and dispose any old TMAP resources with the same ID. This means that you should always be able to save your TileMap, unless the disk gets full.
- The Tiling routines for working with a TileMap are now "separated" from SpriteWorld a bit more. SWCreateTileMap and SWLoadTileMap now only return a TileMapStructPtr to the caller; they don't install the TileMap in the SpriteWorld. You must now do this yourself with SWInstallTileMap. This allows much more freedom when working with TileMaps, since you can load as many TileMaps at a time as you want, and easily switch between them with SWInstallTileMap. Note that existing programs that use the Tiling routines will not work until you add a call to SWInstallTileMap after loading or creating it. See any of the demos that use Tiling for an example of how to use SWInstallTileMap.
Also, since the number of rows and columns can no longer be stored in the SpriteWorld, but must be stored in the TileMap itself (since there may be more than one TileMap loaded at a time), a new structure was created, called the TileMapStruct, that contains the pointer to the TileMap array as well as the number of rows and columns in the TileMap. It also contains Handles to the TileMap as well as other information that is used internally by SpriteWorld. This means that you must now pass a TileMapStructPtr to the TileMap functions, instead of passing a TileMapPtr. Also, to access the TileMap, you must now use myTileMapStructP->tileMap[x][y], instead of myTileMap[x][x]. See the documentation for SWCreateTileMap for more information.
- Fixed a problem where the heap could get corrupted if SWDrawTile or SWChangeTileImage were called too many times in a single frame of the animation.
- Idle sprites are now properly redrawn in a non-scrolling animation when overwritten by a tile that changed images.
- Fixed a bug where a portion of an invisible idle sprite could get drawn if the sprite overlapped a tile that had changed images.
- Fixed a problem in SWLoadTileFromCicnResource that could cause the tile to not be drawn correctly if the tile size set with SWInitTiling wasn't a standard CICN size (8X8, 16X16, 32X32, 64X64, etc.) and CopyBits was used. For instance, if the tile size was set to 29X29 and a 32X32 CICN was loaded, the entire 32X32 image may have been scaled to fit inside the 24X24 square when drawn, if CopyBits were used to draw it.
Other changes to SpriteWorld:
- The name of the function SWRemoveSpriteFromAnimation was changed to SWMarkSpriteForRemoval in order to make the name more clearly indicate the true actions of the function, since it doesn't remove the sprite immediately, but marks it to be removed after it has been erased.
- In order to make the SpriteWorld library callable from Pascal, SW_FUNC is now declared as pascal (see SWCommonHeaders.h). The only way this will affect you is that all functions that are called from within SpriteWorld, such as your custom MoveProcs, FrameProcs, CollideProcs, ScrollingWorldMoveProcs, and TileChangeProcs, must now have their function prototypes prefixed with "SW_FUNC". (See any of the demos for an example.)
- SWCreateSpriteWorldFromWindow now requires an additional parameter. Called "maxDepth", this parameter can be used to force SpriteWorld to create its offscreen GWorlds at a depth lower than the current monitor depth. If zero is passed the offscreen GWorlds are made the same depth as the monitor, as before.
- Added a borderWidth parameter to SWCreateSpriteFromSinglePict. Now you're no longer forced to place a 1-pixel border between sprite frames that use this function!
- Added a borderHeight parameter to SWCreateSpriteFromSinglePictXY, so you're no longer forced to use a 1-pixel border between horizontal rows.
- All of the functions that create multiple frames from a single pict (SWCreateSpriteFromSinglePict, SWCreateSpriteFromSinglePictXY, and SWLoadTilesFromPict) are now much faster when creating frames that use region masks. Using kPixelMask is still the fastest method, but the method of creating multiple region masks from a single pict is now faster than it had been.
- SWUpdateScrollingSpriteWorld now calls the SpriteWorld's scrollingWorldMoveProc, if there is one, so that the visScrollRect is correctly positioned before the animation is copied to the screen.
- Fixed the spelling of the frameHasOccured variable of the SpriteWorldRec. It is now spelled frameHasOccurred.
- Modified SWMoveSprite to only move the sprite if the new position is different from the old position, thus avoiding unnecessary redraws if the sprite is moved to the same location it was at previously.
- SWBounceSprite and SWWrapSprite now return a Boolean value indicating whether they bounced/wrapped the sprite. The functions have also been optimized a little bit, so they may be slightly faster than they were previously.
- SWSetScrollingWorldMoveBounds now makes sure the visScrollRect is still within the new moveBounds.
- Changed the name of the GetScreenDepth function in SWGameUtils.c to GetGDeviceDepth to more accurately describe its function. Also added GetDepthFromGlobalRect to SWGameUtils.c.
- Fixed a bug in the scrolling engine where pieces of idle sprites were getting erased as you scrolled around. In addition, I improved the idle sprite code. Previously, the entire idle sprite was getting redrawn each frame as it scrolled into view. Now only the tiny sliver that has just scrolled into view gets redrawn.
- SWPixelCollision now checks to make sure the srcSpriteP is an 8-bit sprite, and if it is not, the function returns 0 (false). It's up to you to check the depth before calling this function, and to use an alternate routine such as SWRegionCollision if you're not in 8-bit.
- Added a userData variable to the Frame structure. Now you can easily store custom information about each individual frame of a sprite. Just put a pointer here to your custom record, and you can store more than a long's worth of data.
- SWInstallTileMap no longer checks to make sure the tileMapStructP passed to the function is not NULL. This is so you can use this function to set the current tileMap to NULL if you've disposed it with SWDisposeTileMap. This also means SWInstallTileMap no longer returns an error code.
- Several other minor internal changes and fixes.
New functions:
- A whole package for doing scaling, rotating, translucency, and lighting effects have been added, and are available in the SpriteWorld Files->Utils->Brian's Extensions folder. There you will find complete source code as well as documentation for the routines.
- A bunch of routines for handling split-screen scrolling and circular scrolling have been added. See the file "Multi-Screen Scrolling" in the "Add-On Docs" folder of your Documentation folder for more info.
- Added SWWindowMoved. If you're using direct-to-screen blitting, calling this routine whenever the user drags a window will allow direct-to-screen blitting to be used with movable windows.
- Added SWSetPostEraseCallBack and SWSetPostDrawCallBack. These allow you to provide a callback function to be called from SWAnimate after it erases and draws the sprites.
- Added SWChangeWorldRect, which allows you to change the size and location of a SpriteWorld's worldRect without having to dispose and recreate the SpriteWorld.
- Added SWFastAnimateScrollingSpriteWorld which updates only the portions of a scrolling animation that have changed since the previous frame. Note that I do *not* recommend this for use by a game, since the scrolling will dramatically slow down when you start scrolling, and suddenly speed up when you stop. However, this function is great for level editors, since you can quickly update the screen after the user changes a tile.
- SWFlagRectAsChanged lets you tell SpriteWorld when you have changed something in the background frame of the SpriteWorld. Simply call SWFlagRectAsChanged, passing a rect containing the area that you changed, and SpriteWorld will automatically copy that rectangle to the work area and to the screen during the next call to SWAnimate, and will also redraw any idle sprites that were erased by that rectangle when it was copied to the work area.
- SWCheckSpriteWithTiles allows you to quickly and easily determine if a Sprite has come in contact with any Tile in a specified set of Tiles. It also has an option to move the sprite off the tile it ran into, which is great for sprites that run into walls.
- SWReturnTileUnderPixel returns the tileID of the tile under pixelCol and pixelRow. You could do this pretty easily yourself, but this function makes it slightly more convenient.
- SWSetSpriteFrameAdvanceMode allows you to change the automatic frame advancement mode, so that when a sprite's frame index is advanced in SWProcessSpriteWorld and the frames of a sprite reach the last or first frame, the frame advancement either wraps around, or changes direction and goes the other way. Previously SpriteWorld always wrapped them around, so that when advancing past the last frame of the sprite, the first frame would be the next one to be drawn. Now you can tell SpriteWorld to simply change the direction of the frame advancement when it reaches the last or first frame, instead of wrapping around. Although this could have been accomplished by creating a FrameProc to handle this, it is slightly more efficient if SpriteWorld handles it itself.
- SWCopyFrame lets you duplicate a Frame.
- SWUpdateFrameMasks allows you to modify a Frame's image, and then update the masks for that Frame to match the Frame image.
- SWFastCloneSprite provides a slightly faster alternative to SWCloneSprite, but has several side-effects. Read the documentation in Inside SpriteWorld for more info.
- SWSetFrameHotSpot allows you to specify the hotSpot for each Frame of a Sprite. This can be particularly useful when you have a Frame that changes sizes, and you need a way to tell SpriteWorld how the Frame should be positioned relative to the previous Frame.
- SWSetTransparentColor lets you load self-masking sprites which use a color other than white as their transparent color. See the documentation for this function in Inside SpriteWorld for the details.
- RestoreSystemPalette has been added to GameUtils.c. Few of the files in the "Utils" folder are documented, so look at the source code to get a brief description of each function.
New Demos:
- Added Shark Attack, which demonstrates how to use SpriteWorld in an actual game. This program demonstrates things such as how to add and remove sprites from an animation on the fly, how to perform collision detection, and in general, how to set things up properly for a game.
- Added a Split-Screen Scrolling demo, accompanied by brand-new routines for doing split-screen scrolling. (Actually, you can have more than two screens - you can have as many as you want!)
- Various other demos are included in the SpriteWorld 2.1 Extra Demos package, available from wherever you downloaded SpriteWorld.
Changes to the distribution package:
- Updated all source code to be compatible with the latest version of the Universal Headers that come with CodeWarrior Pro and are also available via Apple's web site. This means that the source code is no longer compatible with earlier versions of the Universal Headers. You can either update to the latest headers, or modify the SpriteWorld source files so they are compatible with the older headers again. For more information, read the "About These Demos" file in the SpriteWorld Examples folder. Also see this document for information about getting the PPC demos to run with CodeWarrior Pro.
- All warnings generated when compiling a project with CodeWarrior have been fixed!
- A new package containing additional demos for SpriteWorld was created, called "SpriteWorld 2.1 Demos", so it will show up next to SpriteWorld 2.1 when listed in libraries like InfoMac. It is recommended that you download this package as well - it contains addition demos, such as the Large Background Scrolling, the source code to the Wrapping Illustration, and three new demos by Brian Roddy that demonstrate his utilities for lighting, translucency, scaling, and rotating. You're welcome to contribute your own demos too; if you have something you think other users might want to see, send it to me (Vern), and I'll consider adding it to the package.
- Many additions to the SpriteWorld FAQ and SpriteWorld Tips and Tricks files.
- Cleaned up the code for the Simple demo. Although at first glance it may seem to be more complex, I believe that when you take a closer look, you'll find that it is much easier to read and understand, as well as a much better example of how you should set up your own projects. I figured that if people were basing their own games on this demo, it had better be a proper demonstration of how to set up and run an animation!
- All of the PPC applications except for SpriteTest were removed to cut down on the size of the SpriteWorld package. You can easily make your own PPC demos by compiling the PPC CodeWarrior projects.
- All CodeWarrior projects were updated to CW 10 format so they can be opened by CW Pro.
- Removed all SpriteWorld Library files, since it seems every other release of CodeWarrior changes the library file format. Simply include the SpriteWorld source files directly instead of using libraries in your project. This also enables you to step through the SpriteWorld source code when debugging.
- All projects now require Scrolling.c to be added to the project, regardless of whether your application makes use of the scrolling routines or not. This is because the new SWChangeWorldRect function calls routines in Scrolling.c.
- Greatly improved the error reporting of the SpriteWorld demos that use SWApplication.c. It now not only gives you the error code, but also the file name and line number where the error occurred! If you use the error reporting code in SWApplication.c in your own projects, you'll need to copy the new ALRT, DITL, and STR# resources number 128 from one of the demos that use SWApplication.c into your project for the new error reporting code to work correctly.
